<?php
/**
 * This file defines the exception class {@see \BF\IO\FolderAccessException}
 *
 * @author     Kado <ulfikado@gmail.com>
 * @category   Beluga PHP5.3+ Framework
 * @package    BF\IO
 * @since      2015-01-31 00:29
 * @subpackage Exceptions
 * @version    0.1
 */

namespace BF\IO
{

   /**
    * This exception should be used if accessing a folder for reading and/or writing fails.
    *
    * The class extends from {@see \BF\IO\Exception}.
    *
    * @since v0.1
    */
   class FolderAccessException extends \BF\IO\Exception
   {

      # <editor-fold defaultstate="collapsed" desc=" - - -   C O N S T A N T S   - - - - - - - - - - - - - - - - - - - - - - - - - - -">

      /**
       * Reading folder access.
       */
      const ACCESS_READ = 'read';

      /**
       * Writing folder access.
       */
      const ACCESS_WRITE = 'write';

      /**
       * Reading and writing folder access.
       */
      const ACCESS_READWRITE = 'read and write';

      /**
       * Creating folder access.
       */
      const ACCESS_CREATE = 'create';

      /**
       * Deleting folder access.
       */
      const ACCESS_DELETE = 'delete';

      # </editor-fold>

      # <editor-fold defaultstate="collapsed" desc=" - - -   P R I V A T E   F I E L D S   - - - - - - - - - - - - - - - - - - - - - -">

      private $access;

      # </editor-fold>

      # <editor-fold defaultstate="collapsed" desc=" - - >   P U B L I C   C O N S T R U C T O R   - - - - - - - - - - - - - - - - - -">

      /**
       * Inits a new instance.
       *
       * @param string     $folder   The folder where accessing fails.
       * @param string     $access   The access type (see \BF\IO\FolderAccessException::ACCESS_* class constants)
       * @param string     $message  The optional error message
       * @param integer    $code     A optional error code (Defaults to \E_USER_ERROR)
       * @param \Exception $previous A Optional previous exception.
       */
      public function __construct(
         $folder, $access = self::ACCESS_READ, $message = null, $code = 256, \Exception $previous = null )
      {
         parent::__construct(
            $folder,
            \sprintf( 'Could not %s folder.', $access ) . $this->appendMessage( $message ),
            $code,
            $previous
         );
      }

      # </editor-fold>

      # <editor-fold defaultstate="collapsed" desc=" - - -   P U B L I C   M E T H O D S   - - - - - - - - - - - - - - - - - - - - - -">

      /**
       * Returns the error folder access type (see \BF\IO\FolderAccessException::ACCESS_* class costants)
       *
       * @return string
       */
      public final function getAccessType()
      {
         return $this->access;
      }

      # </editor-fold>

      # <editor-fold defaultstate="collapsed" desc=" - - -   P U B L I C   S T A T I C   M E T H O D S   - - - - - - - - - - - - - - -">

      /**
       * Inits a new \BF\IO\FolderAccessException for folder read mode.
       *
       * @param  string     $folder   The folder where reading fails.
       * @param  string     $message  The optional error message.
       * @param  integer    $code     A optional error code (Defaults to \E_USER_ERROR)
       * @param  \Exception $previous A Optional previous exception.
       * @return \BF\IO\FolderAccessException
       */
      public static function Read( $folder, $message = null, $code = \E_USER_ERROR, \Exception $previous = null )
      {
         return new \BF\IO\FolderAccessException (
            $folder,
            \BF\IO\FolderAccessException::ACCESS_READ,
            $message,
            $code,
            $previous
         );
      }

      /**
       * Inits a new \BF\IO\FolderAccessException for folder write mode.
       *
       * @param  string     $folder   The folder where reading fails.
       * @param  string     $message  The optional error message.
       * @param  integer    $code     A optional error code (Defaults to \E_USER_ERROR)
       * @param  \Exception $previous A Optional previous exception.
       * @return \BF\IO\FolderAccessException
       */
      public static function Write( $folder, $message = null, $code = \E_USER_ERROR, \Exception $previous = null )
      {
         return new \BF\IO\FolderAccessException (
            $folder,
            \BF\IO\FolderAccessException::ACCESS_WRITE,
            $message,
            $code,
            $previous
         );
      }

      # </editor-fold>

   }

}

